Test di Integrazione: Padroneggiare il Test delle API con Supertest

Nel mondo dello sviluppo software, assicurarsi che i singoli componenti funzionino correttamente in isolamento (test unitari) è fondamentale. Tuttavia, è altrettanto importante verificare che questi componenti lavorino insieme senza problemi. È qui che entra in gioco il test di integrazione. Il test di integrazione si concentra sulla validazione dell'interazione tra diversi moduli o servizi all'interno di un'applicazione. Questo articolo approfondisce il test di integrazione, concentrandosi in particolare sul test delle API con Supertest, una libreria potente e facile da usare per testare le asserzioni HTTP in Node.js.

Cos'è il Test di Integrazione?

Il test di integrazione è un tipo di test del software che combina singoli moduli software e li testa come un gruppo. Ha lo scopo di esporre i difetti nelle interazioni tra le unità integrate. A differenza dei test unitari, che si concentrano sui singoli componenti, il test di integrazione verifica il flusso di dati e il flusso di controllo tra i moduli. Gli approcci comuni al test di integrazione includono:

• Integrazione top-down: Si parte dai moduli di livello più alto e si integra verso il basso.
• Integrazione bottom-up: Si parte dai moduli di livello più basso e si integra verso l'alto.
• Integrazione big-bang: Si integrano tutti i moduli contemporaneamente. Questo approccio è generalmente meno raccomandato a causa della difficoltà nell'isolare i problemi.
• Integrazione a sandwich: Una combinazione di integrazione top-down e bottom-up.

Nel contesto delle API, il test di integrazione implica la verifica che diverse API funzionino correttamente insieme, che i dati passati tra di esse siano coerenti e che il sistema complessivo funzioni come previsto. Ad esempio, immaginate un'applicazione di e-commerce con API separate per la gestione dei prodotti, l'autenticazione degli utenti e l'elaborazione dei pagamenti. Il test di integrazione assicurerebbe che queste API comunichino correttamente, consentendo agli utenti di sfogliare i prodotti, accedere in modo sicuro e completare gli acquisti.

Perché il Test di Integrazione delle API è Importante?

Il test di integrazione delle API è fondamentale per diverse ragioni:

• Garantisce l'Affidabilità del Sistema: Aiuta a identificare i problemi di integrazione nelle prime fasi del ciclo di sviluppo, prevenendo guasti imprevisti in produzione.
• Valida l'Integrità dei Dati: Verifica che i dati vengano trasmessi e trasformati correttamente tra le diverse API.
• Migliora le Prestazioni dell'Applicazione: Può scoprire colli di bottiglia nelle prestazioni legati alle interazioni tra API.
• Aumenta la Sicurezza: Può identificare vulnerabilità di sicurezza derivanti da un'integrazione API impropria. Ad esempio, garantendo un'autenticazione e un'autorizzazione corrette quando le API comunicano.
• Riduce i Costi di Sviluppo: Risolvere i problemi di integrazione in anticipo è significativamente più economico che affrontarli più avanti nel ciclo di vita dello sviluppo.

Considerate una piattaforma globale di prenotazione viaggi. Il test di integrazione delle API è fondamentale per garantire una comunicazione fluida tra le API che gestiscono le prenotazioni di voli, le prenotazioni di hotel e i gateway di pagamento di vari paesi. Una mancata integrazione corretta di queste API potrebbe portare a prenotazioni errate, fallimenti nei pagamenti e una scarsa esperienza utente, con un impatto negativo sulla reputazione e sui ricavi della piattaforma.

Vi presentiamo Supertest: Uno Strumento Potente per il Test delle API

Supertest è un'astrazione di alto livello per il test delle richieste HTTP. Fornisce un'API comoda e fluente per inviare richieste alla vostra applicazione e asserire sulle risposte. Basato su Node.js, Supertest è progettato specificamente per testare i server HTTP di Node.js. Funziona eccezionalmente bene con framework di test popolari come Jest e Mocha.

Caratteristiche Principali di Supertest:

• Facile da Usare: Supertest offre un'API semplice e intuitiva per inviare richieste HTTP ed effettuare asserzioni.
• Test Asincrono: Gestisce in modo trasparente le operazioni asincrone, rendendolo ideale per testare API che si basano su logica asincrona.
• Interfaccia Fluente: Fornisce un'interfaccia fluente, permettendovi di concatenare i metodi per ottenere test concisi e leggibili.
• Supporto Completo per le Asserzioni: Supporta un'ampia gamma di asserzioni per verificare i codici di stato, gli header e i body delle risposte.
• Integrazione con i Framework di Test: Si integra perfettamente con i framework di test più diffusi come Jest e Mocha, consentendovi di utilizzare la vostra infrastruttura di test esistente.

Configurazione dell'Ambiente di Test

Prima di iniziare, configuriamo un ambiente di test di base. Partiremo dal presupposto che abbiate installato Node.js e npm (o yarn). Useremo Jest come framework di test e Supertest per il test delle API.

1. Creare un progetto Node.js:

            mkdir api-testing-example
cd api-testing-example
npm init -y
            

              
                Copy
              
            
          

2. Installare le dipendenze:

            npm install --save-dev jest supertest
npm install express  # O il vostro framework preferito per creare l'API
            

              
                Copy
              
            
          

3. Configurare Jest: Aggiungete quanto segue al vostro file package.json:

            {
  "scripts": {
    "test": "jest"
  }
}
            

              
                Copy
              
            
          

4. Creare un endpoint API semplice: Create un file chiamato app.js (o simile) con il seguente codice:

            const express = require('express');
const app = express();
const port = 3000;

app.get('/hello', (req, res) => {
  res.send('Hello, World!');
});

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`);
});

module.exports = app; // Esporta per il testing

            

              
                Copy
              
            
          

Scrivere il Vostro Primo Test con Supertest

Ora che abbiamo configurato il nostro ambiente, scriviamo un semplice test con Supertest per verificare il nostro endpoint API. Create un file chiamato app.test.js (o simile) nella root del vostro progetto:

            const request = require('supertest');
const app = require('./app');

describe('GET /hello', () => {
  it('responds with 200 OK and returns "Hello, World!"', async () => {
    const response = await request(app).get('/hello');
    expect(response.statusCode).toBe(200);
    expect(response.text).toBe('Hello, World!');
  });
});

            

              
                Copy
              
            
          

Spiegazione:

• Importiamo supertest e la nostra app Express.
• Usiamo describe per raggruppare i nostri test.
• Usiamo it per definire un caso di test specifico.
• Usiamo request(app) per creare un agente Supertest che effettuerà richieste alla nostra app.
• Usiamo .get('/hello') per inviare una richiesta GET all'endpoint /hello.
• Usiamo await per attendere la risposta. I metodi di Supertest restituiscono delle promise, permettendoci di usare async/await per un codice più pulito.
• Usiamo expect(response.statusCode).toBe(200) per asserire che il codice di stato della risposta sia 200 OK.
• Usiamo expect(response.text).toBe('Hello, World!') per asserire che il corpo della risposta sia "Hello, World!".

Per eseguire il test, lanciate il seguente comando nel vostro terminale:

            npm test
            

              
                Copy
              
            
          

Se tutto è configurato correttamente, dovreste vedere il test passare.

Tecniche Avanzate di Supertest

Supertest offre una vasta gamma di funzionalità per il test avanzato delle API. Esploriamone alcune.

1. Inviare Corpi di Richiesta

Per inviare dati nel corpo della richiesta, potete usare il metodo .send(). Ad esempio, creiamo un endpoint che accetta dati JSON:

            app.post('/users', express.json(), (req, res) => {
  const { name, email } = req.body;
  // Simula la creazione di un utente in un database
  const user = { id: Date.now(), name, email };
  res.status(201).json(user);
});
            

              
                Copy
              
            
          

Ecco come potete testare questo endpoint usando Supertest:

            describe('POST /users', () => {
  it('creates a new user', async () => {
    const userData = {
      name: 'John Doe',
      email: 'john.doe@example.com',
    };

    const response = await request(app)
      .post('/users')
      .send(userData)
      .expect(201);

    expect(response.body).toHaveProperty('id');
    expect(response.body.name).toBe(userData.name);
    expect(response.body.email).toBe(userData.email);
  });
});
            

              
                Copy
              
            
          

Spiegazione:

• Usiamo .post('/users') per inviare una richiesta POST all'endpoint /users.
• Usiamo .send(userData) per inviare l'oggetto userData nel corpo della richiesta. Supertest imposta automaticamente l'header Content-Type su application/json.
• Usiamo .expect(201) per asserire che il codice di stato della risposta sia 201 Created.
• Usiamo expect(response.body).toHaveProperty('id') per asserire che il corpo della risposta contenga una proprietà id.
• Usiamo expect(response.body.name).toBe(userData.name) e expect(response.body.email).toBe(userData.email) per asserire che le proprietà name e email nel corpo della risposta corrispondano ai dati che abbiamo inviato nella richiesta.

2. Impostare gli Header

Per impostare header personalizzati nelle vostre richieste, potete usare il metodo .set(). Questo è utile per impostare token di autenticazione, tipi di contenuto o altri header personalizzati.

            describe('GET /protected', () => {
  it('requires authentication', async () => {
    const response = await request(app).get('/protected').expect(401);
  });

  it('returns 200 OK with a valid token', async () => {
    // Simula l'ottenimento di un token valido
    const token = 'valid-token';

    const response = await request(app)
      .get('/protected')
      .set('Authorization', `Bearer ${token}`)
      .expect(200);

    expect(response.text).toBe('Protected Resource');
  });
});
            

              
                Copy
              
            
          

Spiegazione:

• Usiamo .set('Authorization', `Bearer ${token}`) per impostare l'header Authorization su Bearer ${token}.

3. Gestione dei Cookie

Supertest può anche gestire i cookie. Potete impostare i cookie usando il metodo .set('Cookie', ...), oppure potete usare la proprietà .cookies per accedere e modificare i cookie.

4. Testare l'Upload di File

Supertest può essere usato per testare endpoint API che gestiscono l'upload di file. Potete usare il metodo .attach() per allegare file alla richiesta.

5. Usare Librerie di Asserzioni (Chai)

Sebbene la libreria di asserzioni integrata di Jest sia sufficiente per molti casi, potete anche usare librerie di asserzioni più potenti come Chai con Supertest. Chai fornisce una sintassi di asserzione più espressiva e flessibile. Per usare Chai, dovrete installarlo:

            npm install --save-dev chai
            

              
                Copy
              
            
          

Poi, potete importare Chai nel vostro file di test e usare le sue asserzioni:

            const request = require('supertest');
const app = require('./app');
const chai = require('chai');
const expect = chai.expect;

describe('GET /hello', () => {
  it('responds with 200 OK and returns "Hello, World!"', async () => {
    const response = await request(app).get('/hello');
    expect(response.statusCode).to.equal(200);
    expect(response.text).to.equal('Hello, World!');
  });
});
            

              
                Copy
              
            
          

Nota: Potrebbe essere necessario configurare Jest per funzionare correttamente con Chai. Questo spesso comporta l'aggiunta di un file di setup che importa Chai e lo configura per funzionare con l'expect globale di Jest.

6. Riutilizzare gli Agenti

Per i test che richiedono la configurazione di un ambiente specifico (es. autenticazione), è spesso vantaggioso riutilizzare un agente Supertest. Ciò evita codice di setup ridondante in ogni caso di test.

            describe('Authenticated API Tests', () => {
  let agent;

  beforeAll(() => {
    agent = request.agent(app); // Crea un agente persistente
    // Simula l'autenticazione
    return agent
      .post('/login')
      .send({ username: 'testuser', password: 'password123' });
  });

  it('can access a protected resource', async () => {
    const response = await agent.get('/protected').expect(200);
    expect(response.text).toBe('Protected Resource');
  });

  it('can perform other actions that require authentication', async () => {
    // Esegui qui altre azioni che richiedono autenticazione
  });
});
            

              
                Copy
              
            
          

In questo esempio, creiamo un agente Supertest nell'hook beforeAll e autentichiamo l'agente. I test successivi all'interno del blocco describe possono quindi riutilizzare questo agente autenticato senza doversi ri-autenticare per ogni test.

Best Practice per il Test di Integrazione delle API con Supertest

Per garantire un test di integrazione delle API efficace, considerate le seguenti best practice:

• Testare Flussi di Lavoro End-to-End: Concentratevi sul testare flussi di lavoro utente completi piuttosto che endpoint API isolati. Questo aiuta a identificare problemi di integrazione che potrebbero non essere evidenti testando le singole API in isolamento.
• Usare Dati Realistici: Usate dati realistici nei vostri test per simulare scenari del mondo reale. Ciò include l'uso di formati di dati validi, valori limite e dati potenzialmente non validi per testare la gestione degli errori.
• Isolare i Vostri Test: Assicuratevi che i vostri test siano indipendenti l'uno dall'altro e che non si basino su uno stato condiviso. Questo renderà i vostri test più affidabili e facili da debuggare. Considerate l'uso di un database di test dedicato o il mocking delle dipendenze esterne.
• Mockare le Dipendenze Esterne: Usate il mocking per isolare la vostra API dalle dipendenze esterne, come database, API di terze parti o altri servizi. Questo renderà i vostri test più veloci e affidabili, e vi permetterà anche di testare diversi scenari senza dipendere dalla disponibilità di servizi esterni. Librerie come nock sono utili per il mocking delle richieste HTTP.
• Scrivere Test Completi: Puntate a una copertura di test completa, includendo test positivi (che verificano risposte corrette), test negativi (che verificano la gestione degli errori) e test dei casi limite (che verificano i casi estremi).
• Automatizzare i Vostri Test: Integrate i vostri test di integrazione API nella vostra pipeline di integrazione continua (CI) per assicurarvi che vengano eseguiti automaticamente ogni volta che vengono apportate modifiche al codebase. Questo aiuterà a identificare i problemi di integrazione in anticipo e a prevenire che raggiungano la produzione.
• Documentare i Vostri Test: Documentate i vostri test di integrazione API in modo chiaro e conciso. Questo renderà più facile per gli altri sviluppatori capire lo scopo dei test e mantenerli nel tempo.
• Usare Variabili d'Ambiente: Memorizzate informazioni sensibili come chiavi API, password di database e altri valori di configurazione in variabili d'ambiente piuttosto che scriverle direttamente nel codice dei vostri test. Questo renderà i vostri test più sicuri e più facili da configurare per ambienti diversi.
• Considerare i Contratti API: Utilizzate il test dei contratti API per convalidare che la vostra API aderisca a un contratto definito (es. OpenAPI/Swagger). Questo aiuta a garantire la compatibilità tra i diversi servizi e previene le "breaking changes". Strumenti come Pact possono essere usati per il test dei contratti.

Errori Comuni da Evitare

• Non isolare i test: I test dovrebbero essere indipendenti. Evitate di fare affidamento sull'esito di altri test.
• Testare i dettagli di implementazione: Concentratevi sul comportamento e sul contratto dell'API, non sulla sua implementazione interna.
• Ignorare la gestione degli errori: Testate a fondo come la vostra API gestisce input non validi, casi limite ed errori imprevisti.
• Saltare i test di autenticazione e autorizzazione: Assicuratevi che i meccanismi di sicurezza della vostra API siano testati correttamente per prevenire accessi non autorizzati.

Conclusione

Il test di integrazione delle API è una parte essenziale del processo di sviluppo del software. Utilizzando Supertest, potete scrivere facilmente test di integrazione API completi e affidabili che aiutano a garantire la qualità e la stabilità della vostra applicazione. Ricordate di concentrarvi sul testare i flussi di lavoro end-to-end, usando dati realistici, isolando i vostri test e automatizzando il processo di testing. Seguendo queste best practice, potete ridurre significativamente il rischio di problemi di integrazione e fornire un prodotto più robusto e affidabile.

Mentre le API continuano a guidare le applicazioni moderne e le architetture a microservizi, l'importanza di test API robusti, e in particolare dei test di integrazione, non farà che crescere. Supertest fornisce un set di strumenti potente e accessibile per gli sviluppatori di tutto il mondo per garantire l'affidabilità e la qualità delle loro interazioni API.